Other issue¶

What should I do if the device becomes excessively hot?¶

Confirm whether the temperature is actually too high¶

Run the following command to obtain the current device temperature:

qpi-config dump temperature

If the temperature exceeds 80 °C, take cooling measures immediately.

Identify the heat source¶

Check CPU utilization and frequency:

# Check CPU utilization.
top -b -n 1 | head -20

# Check the operating frequency of each CPU core to determine whether it remains at the maximum frequency.
cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_cur_freq

# Check whether the performance governor is enabled.
cat /sys/devices/system/cpu/cpu*/cpufreq/scaling_governor

Check GPU utilization:

cat /sys/class/kgsl/kgsl-3d0/gpu_busy_percentage 2>/dev/null
cat /sys/class/kgsl/kgsl-3d0/max_gpuclk 2>/dev/null

Check storage utilization:

iostat -x 1 3   # Check %util.

Software cooling measures¶

Lower the CPU frequency:

# Check available frequencies.
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_available_frequencies

# Set the maximum frequency, for example, to 1.6 GHz.
echo 1651200 > /sys/devices/system/cpu/cpu0/cpufreq/scaling_max_freq

Switch the CPU governor to schedutil:

echo schedutil > /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor

Lower the maximum GPU operating frequency:

# Check available frequencies.
cat /sys/class/kgsl/kgsl-3d0/devfreq/available_frequencies

# Set the maximum frequency, for example, to 550 MHz.
echo 550000000 > /sys/class/kgsl/kgsl-3d0/devfreq/max_freq

Check for processes with abnormal CPU usage:

ps aux --sort=-%cpu | head -10

Physical cooling measures¶

Place the Quectel Pi H1 in a well-ventilated environment.
Install an active cooling module. The fan should increase its speed automatically when the device temperature exceeds the configured threshold.

What should I do if a library does not work correctly?¶

Identify and classify the issue¶

Link error: The compiler reports cannot find -lxxx, or the error cannot open shared object file occurs at runtime.
Runtime crash: The application reports undefined symbol: xxx or triggers a Segmentation fault.
Functional error: The library loads successfully, but a specific API does not respond or returns an unexpected error code.

Check whether the library file exists and verify the library search path¶

# 1. Locate the library.
find /usr/lib /usr/local/lib /lib -name "libxxx.so*"

# 2. Check whether the dynamic linker can locate the library.
ldconfig -p | grep libxxx

# 3. Check whether LD_LIBRARY_PATH contains the directory.
echo $LD_LIBRARY_PATH

If the library is in a nonstandard directory, set LD_LIBRARY_PATH, or add the directory to a configuration file under /etc/ld.so.conf.d/ and run ldconfig to update the cache.

Check dependencies to resolve undefined symbols¶

# Check the library dependencies (safer than ldd because it does not execute code).
readelf -d /path/to/libxxx.so | grep NEEDED

# Check whether a symbol is defined in the library.
nm -D /path/to/libxxx.so | grep "  T " | grep symbol_name

# Alternatively:
readelf -s /path/to/libxxx.so | grep symbol_name

An undefined symbol usually indicates a library version mismatch or a missing dependency. If the symbol exists but the application still reports an error, the cause may be link order or ABI incompatibility.

Check library version and ABI compatibility¶

# Check the embedded library version string.
strings /path/to/libxxx.so | grep -i version

# Check the library's SONAME (the name used by the dynamic linker).
readelf -d /path/to/libxxx.so | grep SONAME

If the application was linked against libxxx.so.1 at build time but the system provides only libxxx.so.2, ABI incompatibility may still cause the application to crash at runtime even if the newer library exports the required symbols. After confirming that the two library versions are ABI-compatible, you can create a symbolic link (ln -s libxxx.so.2 libxxx.so.1) as a temporary workaround. For a long-term solution, install a library version compatible with the application or rebuild the application against the library available on the system.

Trace dynamic library loading at runtime (to diagnose loading failures)¶

# 1. Check which libraries the dynamic linker loads and whether it loads an incorrect version.
LD_DEBUG=libs ./your_app 2>&1 | grep libxxx

# 2. Use strace to trace attempts to open library files.
strace -e openat,open ./your_app 2>&1 | grep libxxx

# 3. If the application crashes immediately after startup, use gdb to locate the crash.
gdb ./your_app
(gdb) run
(gdb) bt   # Check the call stack after the crash.

How can I update a third-party driver?¶

Obtain the official SDK. See Image build for download instructions.
Add the third-party driver source code under sources/quectel-src/kernel.
Add the device tree node for the peripheral to sources/quectel-src/kernel/qcom-6.6/arch/arm64/boot/dts/qcom/qcs6490-idp-pi.dts.
Build the system image, flash it to the Quectel Pi H1, and then test the driver functionality.

What should I do if system performance is poor?¶

Poor performance is usually caused by a combination of CPU scheduling, memory pressure, storage I/O, thermal throttling, and software configuration.

Identify the bottleneck¶

# 1. Check the overall system load (1/5/15 minute).
uptime
# A sustained load average above the number of CPU cores (for example, above 8.0 on an 8-core system) indicates insufficient CPU capacity.

# 2. Check CPU utilization by state (user, system, soft interrupt, and idle).
mpstat -P ALL 1 3

# 3. Check memory and swap usage (whether swap is in use).
free -h
# Less than 10% available memory with nonzero swap usage indicates memory pressure.

# 4. Check for a storage I/O bottleneck (a %util value close to 100% indicates that the disk is a bottleneck).
iostat -x 1 3

# 5. Check the temperature and CPU frequency (determine whether thermal throttling has occurred).
qpi-config dump temperature
cat /sys/devices/system/cpu/cpu0/cpufreq/scaling_cur_freq

Interpret the key metrics as follows:

High %us: CPU-intensive tasks.
High %sy: Excessive system call or driver overhead (such as software interrupt).
High %wa: Storage I/O bottleneck.
High %si: Excessive software interrupts (such as BLOCK softirq).
Temperature above 80 °C: Potential thermal throttling.
Very little available memory in free -h: Memory pressure.

Apply targeted optimization¶

CPU bottleneck (%us or %sy consistently above 60%)¶

Identify the processes with the highest CPU utilization.
Reduce the load generated by cameras and other peripherals.
Increase the real-time priority of critical threads, for example, by adjusting the scheduling policy.

Memory bottleneck ( low available memory and nonzero swap usage)¶

Identify the Top 10 processes with the highest memory usage.
Remove unnecessary log files.
Check for DMA-BUF or ION memory leaks.

Storage I/O bottleneck (%util in iostat close to 100%)¶

Identify the process with the highest write I/O activity.
Reduce unnecessary log writes.
Check for processes that write files too frequently.

Thermal throttling (frequency reduction caused by high temperature)¶

Confirm whether the system has triggered frequency throttling.
Apply active physical or software cooling measures.

How can I configure a service to start at boot?¶

systemd is the standard init system used by most mainstream Linux distributions, including Yocto-based systems. It provides dependency management, automatic restart, and environment variable configuration.

Create a service unit file¶

Create a .service file under /etc/systemd/system/ such as my-camera.service:

[Unit]
Description=My Camera Service
After=network.target   # Start after the network is available (adjust as needed).

[Service]
Type=simple            # Other types include forking and oneshot.
ExecStart=/usr/bin/my_script.sh
Restart=on-failure     # Restart automatically after a failure.
User=root              # Specify the user that runs the service (typically root).
WorkingDirectory=/opt/my_app

[Install]
WantedBy=multi-user.target   # Start the service when the system enters multi-user mode.

Enable and start the service¶

# Reload the systemd configuration.
sudo systemctl daemon-reload

# Enable the service to start at boot (creates a symbolic link).
sudo systemctl enable my-camera.service

# Start the service immediately (optional).
sudo systemctl start my-camera.service

# Check the service status.
sudo systemctl status my-camera.service

How can I install a third-party driver?¶

Obtain the driver module file: Obtain the third-party driver source code and cross-compile it in an environment that matches the Quectel Pi H1’s kernel version to generate a .ko module file.
Transfer the driver module file: Transfer the compiled .ko file to the Quectel Pi H1 through scp, adb, or a USB flash drive.
Load and unload the driver:
Run insmod to load the driver:

insmod your_driver.ko

Run rmmod to unload the driver:

rmmod your_driver

Run lsmod to list all loaded modules:

lsmod

What should I do if no solution is available?¶

Visit Technical FAQs.
Post a question on the Quectel Forums.